Crate cust

Safe, Fast, and user-friendly wrapper around the CUDA Driver API.

Low level CUDA interop

Because additions to CUDA and libraries that use CUDA are everchanging, this library provides unsafe functions for retrieving and setting handles to raw cuda_sys objects. This allows advanced users to embed libraries that rely on CUDA, such as OptiX. We also re-export cuda_sys as a sys module for convenience.

CUDA Terminology:

Devices and Hosts:

This crate and its documentation uses the terms “device” and “host” frequently, so it’s worth explaining them in more detail. A device refers to a CUDA-capable GPU or similar device and its associated external memory space. The host is the CPU and its associated memory space. Data must be transferred from host memory to device memory before the device can use it for computations, and the results must then be transferred back to host memory.

Contexts, Modules, Streams and Functions:

A CUDA context is akin to a process on the host - it contains all of the state for working with a device, all memory allocations, etc. Each context is associated with a single device.

A Module is similar to a shared-object library - it is a piece of compiled code which exports functions and global values. Functions can be loaded from modules and launched on a device as one might load a function from a shared-object file and call it. Functions are also known as kernels and the two terms will be used interchangeably.

A Stream is akin to a thread - asynchronous work such as kernel execution can be queued into a stream. Work within a single stream will execute sequentially in the order that it was submitted, and may interleave with work from other streams.

Grids, Blocks and Threads:

CUDA devices typically execute kernel functions on many threads in parallel. These threads can be grouped into thread blocks, which share an area of fast hardware memory known as shared memory. Thread blocks can be one-, two-, or three-dimensional, which is helpful when working with multi-dimensional data such as images. Thread blocks are then grouped into grids, which can also be one-, two-, or three-dimensional.

CUDA devices often contain multiple separate processors. Each processor is capable of excuting many threads simultaneously, but they must be from the same thread block. Thus, it is important to ensure that the grid size is large enough to provide work for all processors. On the other hand, if the thread blocks are too small each processor will be under-utilized and the code will be unable to make effective use of shared memory.

Usage:

Before using cust, you must install the CUDA development libraries for your system. Version 9.0 or newer is required. You must also have a CUDA-capable GPU installed with the appropriate drivers.

Cust will try to find the CUDA libraries automatically, if it is unable to find it, you can set CUDA_LIBRARY_PATH to some path manually.

Re-exports

pub use cust_raw as sys;

Modules

context

CUDA Context handling.

device

Functions and types for enumerating CUDA devices and retrieving information about them.

error

Types for error handling

event

Events can be used to track status and dependencies, as well as to measure the duration of work submitted to a CUDA stream.

external

External memory and synchronization resources

function

Functions and types for working with CUDA kernels.

link

Functions for linking together multiple PTX files into a module.

memory

Access to CUDA’s memory allocation and transfer functions.

module

Functions and types for working with CUDA modules.

prelude

This module re-exports a number of commonly-used types for working with cust.

stream

Streams of work for the device to perform.

util

Macros

kernel_invocation

Creates a kernel invocation using the same syntax as [launch] to be used to insert kernel launches inside graphs. This returns a Result of a kernel invocation object you can then pass to a graph.

launch

Launch a kernel function asynchronously.

Structs

CudaApiVersion

Struct representing the CUDA API version number.

CudaFlags

Bit flags for initializing the CUDA driver. Currently, no flags are defined, so CudaFlags::empty() is the only valid value.

Functions

init

Initialize the CUDA Driver API.

quick_init

Shortcut for initializing the CUDA Driver API and creating a CUDA context with default settings for the first device.

Derive Macros

DeviceCopy